Creating Kanban Layouts in a List Control
Description
Visually organize task or project data using the "Kanban" layout with the List control. Items displayed using a Kanban layout can be reorganized within "categories" or moved between categories using drag-and-drop within the List.
Discussion
A Kanban layout is useful if you have List data that can be grouped in categories and you want to be able to drag and drop a row from one category to another, or drag and drop a row with a category to change its order within the category.
Example of the types of data where a Kanban view could be useful include:
- Sales pipeline data where each item in the List can be categorized as Prospect, Qualified, Closed, etc.
- Task list where each item in the List can be categorized as Not Yet Started, In Progress, Completed, Rejected
In the image below, a Kanban layout is shown for sales pipeline data.
A List can have multiple Layouts. Any of the layout can be a Kanban layout. You can switch at any time from one layout (which might be columnar or freeform) to a Kanban layout.
In the image shown above each category has a group footer in which the total for the amount field in that category is shown. The user can click on the hamburger icon and drag the row to a new position within the category, or to a different category.
It is common that when you move a row, you will want to persist the data to a backend database. This is easily done by turning on the List's Detail View property and then putting a button on the UX to synchronize the List data.
To create a Kanban layout, set the Layout type to Kanban.
To configure the Kanban settings click the smart field for the Kanban settings property. This will open the Kanban Layout Setup Genie.
Properties of note in this dialog include:
- Property
- Description
- Category field
This is the field in the List data that contains the various categories
- Category display
The categories in the Kanban layout can either be displayed horizontally (as in the above image), or vertically. On a phone, for example, it is likely that you would want a vertical display.
- Order field
This is the field in the List data that defines the order of the records within a category
- Default category names
This is the List of category names that the Kanban layout should display regardless of whether there is any data in the category or not. For example, in a sales pipeline list you may want to include a Closed category even if none of the records current have a status of Closed. The categories in the Kanban layout are displayed in the same order in which they appear in this property. For example, in the image above, the default categories are Prospect, Qualified, Proposal, Closed and Lost and this is the order in which the Kanban layout will display the categories. If there are no records in a particular record, you can control the HTML that is displayed in the empty category by setting the HTML for empty categories property.
- Sort fields
The data in the List are automatically sorted by the category field and within category by the order field. You can define additional sort criteria. For example, if two records in the same category have the same value in the order field, the sort defined here will break the tie.
- Category header html
This is the HTML that appears at the top of each Category group
- Move icon
This is the icon that is displayed in each row. The user drags on this icon to move a row to a new position.
- Color Javascript
This is optional. You can define a Javascript function that can return a color to use in the Kanban layout. In the above image you will note that all of the records in the Prospect category have an orange edge. Your Javascript code can determine what color to return based on data in the current row. In the above example, the following code was defined in the Color Javascript property:
if(data.Category == 'Qualified') return 'Pink'; if(data.Category == 'Prospect') return 'Orange'; if(data.Category == 'Proposal') return 'Blue'; if(data.Category == 'Closed') return 'Green'; if(data.Category == 'Lost') return 'Red';
- onMove function
This even fires when a row is moved (either to a new position within a category, or from one category to another). Your Javascript code can reference variables that define the source position and target position of the row as well as the Category (if the row is moved to a category that did not previously have any records in it).
- onBeforeMove function
This event fires when the user tries to move an item from one category to another. If the event returns false, the move is cancelled.
Once you have defined the Kanban Layout properties, you will need to define the Kanban Layout. Defining the Kanban Layout is very similar to defining a Layout for a freeform List.
In the screenshot below the layout for the Kanban layout shown above is defined. The layout is an HTML template with placeholders for the data in each List row.
The {kanban:draghandle} placeholder is a special placeholder for the drag handle icon that displays in each row.
Note that the background color in the outer div has been set to: {@[scope].kanbancolor([root])}. This is the client-side templating syntax for calling a Javascript function. The value returned by the function will be used for the background color. See the documentation for client-side templating for more information on how to call Javascript functions in a template. Note that kanbancolor() is a special system generated function that will execute the code you defined in the Color Javascript property when you set the Kanban layout properties.
Note also that the list of placeholder at the left edge of the screen include the {kanban:draghandle} placeholder.
When you are defining a new Kanban layout template, you can get a quick start by clicking on the Pre-defined Templates hyperlink. This will bring up a dialog (shown below) where you can select different sample layout templates.
If the data in the List is based on a SQL database, then it is likely that you will want to save the changes you make to the List back to the SQL database. For example, when you move a row to a new position within a category, or you move a row to a different category, you may want to update the underlying SQL database. This is easily accomplished. First, turn on the List's Detail View by setting the Has Detail View property. If you want to edit the data in the List while you are offline, turn on the Persist data to Local Storage property.
You do not need to actually define a Detail View for the List. Simply turning on the Detail View property is sufficient.
Next, add a button to the UX to synchronize the List data. Your button should execute this code:
{dialog.object}.saveListEdits('name_of_your_list_control',{rows: 'allRows', ajax: { timeOut: 15000, onAjaxFail: function() { } , onDeviceOffline: function() { } } });You can add the synchronize button to your UX by selecting the [List-Detail View-Buttons] item in the Defined Controls section of the UX builder. The advantage of adding the button using this technique is that Alpha Anywhere will add an appropriate Enable expression to the button so that it is only enabled if the List has edits that have not been synchronized.
Collapsible Categories
When defining a Kanban layout, you can specify that a category should be collapsible. When a category is collapsed, the records for the category are hidden and only the category header is shown. As a result, the category consumes less space, allowing you to display more categories on screen than would otherwise be shown.
To add collapsible categories to a Kanban layout, enable the Can collapse categories property in the Kanban Settings. Once enabled, you can define the behavior for collapsing and expanding categories. This includes the mode (clicking a title, icon, or programmatically), customizing icons, and setting initial open and closed state. You can also add JavaScript to execute when a category is collapsed or expanded in two JavaScript Events: onCollapse and onExpand.
- Property
- Description
- Can collapse categories
Enables collapsible categories. If checked, exposes the properties listed below.
- Collapse mode
Defines how a category is expanded or collapsed: when the 'Title' is clicked, when the 'Indicator' icon is clicked, or 'Programmatically' by calling the setGroupCollapse() JavaScript method.
- Collapse icon
The icon shown in the category title bar to indicate that a category is collapsed.
- Expand icon
The icon shown in the category title bar to indicate that a category is expanded.
- onCollapse function
A JavaScript function that is called when any category is collapsed.
- onExpand function
A JavaScript function that is called when any category is expanded.
- Initial display - collapse all
If checked, all categories will be collapsed when the Kanban layout is initially rendered.
- Exceptions - Initially collapsed groups
A list of categories that should be collapsed when the Kanban layout is first rendered.
- Exceptions - Initially expanded groups
A list of categories that should be expanded when the Kanban layout is first rendered. This option is only shown if all categories are configured to be collapsed when the List is initially shown.
For more information about these properties, see Kanban settings.
Expanding/Collapsing a Category
If a Kanban layout has been configured to have collapsible categories, you can expand and collapse categories programmatically using the List object's setGroupCollapse() method. This method can expand or collapse any group in the List:
var lObj = {dialog.object}.getControl('name_of_list_control'); var groupName = 'Argentina'; var mode = false; //false == expand, true == collapse, '' == toggle var showAnimation = true; lObj.setGroupCollapse(groupName,mode,showAnimation);Expanding/Collapsing Multiple Categories
Multiple categories in a Kanban layout can be collapsed or expanded by specifying a group selection object instead of the category name. For example:
var lObj = {dialog.object}.getControl('list1') lObj.setGroupCollapse({groups: 'all'},true,false); // collapse all groups without animationTo expand/collapse specific categories, a match function can be used which computes whether or not a category's collapsed state should change:
lObj.setGroupCollapse({groups: 'match', match: function(groupName,groupData){ if(groupName.match(/^[A-z]/)) return true; // match any group with a name starting with a character return false; }},true); // collapse all groups that the passed in function returns true forSee setGroupCollapse() for more information.
Dynamically Adding Categories at Run-time
JavaScript can be used to modify the categories in a Kanban layout. This is done by adding the category to the groups array in the List's JavaScript object:
var layoutName = 'Default'; //name of the Kanban layout
var newCategory = 'New Category';
var lObj = {dialog.object}.getControl('name_of_list_control');
lObj.layouts[layoutName].group.auto[0].groups.push(newCategory);
lObj.refresh();If the List only has one layout, the layoutName is 'Default'.
Videos
Introduction to Kanban List Layouts
Kanban Lists display data organized by category. Users can move List rows from one category to another using drag and drop. Users can also re-order the data within a category using drag and drop.
In this video we show a List control with both a columnar and a Kanban layout.
Creating a List with a Kanban Layout
In this video we show how a Kanban layout can be defined for a List.
Adding Color Coding and Summary Values to a Kanban Layout
In this video we show some advanced features of a Kanban layout. We show how you can add color coding to the layout (so that List rows in different categories are colored differently and how you can summary data to each category.
Persisting Edits in a Kanban List to a SQL Database
In this video we show how a Kanban List can be based on a SQL database and how edits to the List can be saved in the database.